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1. Introduction 


1.1. OVERVIEW OF IMS AND DMS 

Two systems that provide for accessing and updating data are IMS and DMS. IMS provides 
online inquiry with updating capability; DMS provides access to and updating control of 
data bases stored on direct access devices. Both systems offer the data integrity and data 
security features needed in real time processing. These include: 

= Logging of data modifications 


= Online roliback of erroneous data modifications 


= Security locks on data being updated 


Offline restoration of data files 


1.1.1. Types of Files and Data Structures IMS and DMS Can Access 
IMS action programs can access the following file structures: 

= Sequential access method (SAM) 

a Direct access method (DAM) 

] Indexed sequential access method (ISAM) 

a Multi-indexed random access method (MIRAM) 

= Defined files (logical structure) via defined record management 


The IMS uniform inquiry update element (UNIQUE) accesses files through defined record 
management only. 
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DMS data base records are stored in one or more system access technique (SAT) files. The 
permitted logical data base structures are: 


= Sequential (list) structures 
® Hierarchical (tree) structures 
7 Network structures 


A data record can be a member of more than one structure simultaneously. This allows 
you to access data for a wide variety of applications. The description of the logical 
structure and access methods for an entire data base is called a schema and is written in 
the schema data description language (DDL). The subset of the logical data base 
referenced by any given application program or group of programs is described in a 
subschema by using the subschema DDL. Subschemas let you select only the data and 
structures you need for an application and provide a measure of data base security. 


1.1.2. Languages Used to Write IMS Action Programs and DMS Application Programs 


IMS action programs are written in COBOL, RPG Il, or basic assembler language (BAL). 
IMS also offers UNIQUE, a comprehensive inquiry/update facility that requires no 
programming effort except to define the data structure. 


DMS application programs are written in COBOL and the DMS data manipulation 
language (DML). These programs do not contain any data description for the data base 
records; instead, they specify the applicable subschema. 


In IMS and DMS, I/O is handled by the respective data management system. 


1.2. THE IMS/DMS INTERFACE 


The IMS/DMS interface allows you to access a DMS data base from IMS action programs 
and UNIQUE. This gives the IMS user the advantages of DMS structural flexibility and 
powerful access mechanisms and gives the DMS user easy online access to the data base. 


The IMS system you configure is either single-thread or multithread. In single-thread IMS 
systems, only one action is processed at a time, and actions for different transactions are 
interspersed. Since the duration’ of an action is normally short, IMS can handle 
transactions originating from several terminals concurrently, with very little increase in 
response time. Multithread IMS allows concurrent processing of actions for different 
transactions, with increased throughput. 


The DMS system is multithread. When you combine it with the IMS multithread system, 
you can concurrently process actions for different transactions accessing the data base. 
The DMS system can also handle more than one IMS system concurrently. 


You can expect maximum performance when you use the combination of multithread IMS 
and DMS; however, single-thread IMS and multithread DMS provide acceptable 
performance in many instances. 
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1.3. CAPABILITIES 
The IMS/DMS interface allows you to: 
™ access a DMS data base directly from your COBOL action programs; or 


= use DMS files to build an IMS defined file accessible from your action programs and 
from UNIQUE. 


The same action program can directly access DMS data bases and conventional! data files. 
These file types are: 


# ISAM 
a MIRAM 
= DAM 
= SAM 


An action program accessing a data base can also access an IMS defined file through 
defined record management, provided the defined file does not access the data base. That 
is, both types of data base access are not permitted within the same transaction. UNIQUE 
accesses data bases only through defined record management. 


An IMS defined file can include all or parts of a DMS data base, as well as conventional 
ISAM, DAM, or MIRAM files. 


The IMS/DMS interface has facilities for online and offline recovery. 


1.4. HOW IMS AND DMS INTERFACE 


DMS interfaces with IMS through the data manipulation language (DML) and the DML 
preprocessor. DML statements are embedded in COBOL action programs and IMS data 
definitions to permit access to the data base. Action programs and data definitions 
accessing a data base must be preprocessed by the DML preprocessor before you submit 
them to the COBOL compiler or the data definition processor. 


Action programs accessing DMS through IMS defined record management do not require 
preprocessing. Defined files are accessed by CALL statements in either a COBOL or BAL 
action program. RPG II action programs use standard operations to access defined files. 


An action program communicates with DMS through data stored in the data management 
communications area (DMCA) of the action program. Certain functions require that you 
store data in this area before calling DMS. After a call to DMS, the DMCA contains data 
concerning the outcome of the requested service. Certain error conditions produce 
different error codes depending on whether the call to DMS came from single-thread or 
multithread IMS; these codes are listed in Appendix A. 


For more complete information on the DMCA, refer to the DMS data manipulation 
language user guide/programmer reference, UP-8036 (current version). 
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1.5. SYMBOLS, NOTATIONS, AND DOCUMENTATION REFERENCES IN THIS 


MANUAL 


This manual does not attempt to repeat or replace any material that appears in the IMS or 
DMS manuals. Some material from those manuals overlaps the material in this manual 
because this manual draws the two systems together. Instead of repeating material, we 
reference the manual that provides the most detailed description. 


The symbols and notations used in this manual are consistent with the symbols and 
notations used in the IMS and DMS manuals. The following format conventions are used 
in this manual: 


1, 


2. 


Words that appear in all capitals are reserved words. 

Underlined capitalized words are keywords and are required when the functions in 
which they appear are used, except in the case of defaults. Those capitalized words 
not underlined are optional, and you may include them to improve readability. All 
capitalized words are part of the languages and must be spelled exactly as indicated. 


Capitalized words with a double underline begin a statement and must start on a new 
line. 


Lowercase words are generic terms you must supply. 

Braces { } indicate that you must choose one of the elements within the braces. 
Optionalfunctions are enclosed in brackets [ ]. 

Periods must be used where indicated. 


An ellipsis ... indicates optional repetition of the preceding syntax element. 








© 
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@ 3. When you omit the ON ERROR clause, the option specified in the device media 
control language source is used. 

2.5. NORMAL IMS/DMS TERMINATION 
Usually, you shut down IMS before shutting down DMS. If you try to shut down DMS 
while accesses to the data base are still taking place, the shutdown is not performed and 
you receive an error message indicating the data base is still in use. 
In some circumstances, however, you can shut down DMS without first terminating the 
IMS session. This is because DMS treats IMS as a special case. DMS honors your 
shutdown request provided: 


= All DMS batch applications have terminated. 


= IMS is not accessing the data base. 





This allows you to shut down DMS in an orderly fashion while still letting IMS continue 
with its non-DMS work. 


The master terminal operator shuts down IMS by entering either of two commands: 
@ ZZSHD (for normal termination) 
or 


ZZHLT (for emergency only) 


See the IMS system support functions user guide/programmer reference, UP-8364 
(current version). 


The operator shuts down DMS by entering this unsolicited command at the console: 


nO SHUTDOWN DBMS. 


The variable n in this command is the job slot number of the DBMS job and O indicates to 
OS/3 that this is an unsolicited command. See the DMS system support functions user 
guide/programmer reference, UP-8272 (current version). 


2.6. ABNORMAL IMS TERMINATION 


When IMS is shut down (by ZZHLT, ZZSHD, or an error causing abnormal termination), the 
OS/3 operating system notifies DMS that IMS has terminated (whether IMS termination is 
normal or abnormal). DMS initiates processing of active run-unit termination and rollback, but 
DMS remains running. To reestablish the interface, restart IMS by using the warm or cold 

@ restart procedure. For a detailed description on restarting IMS, refer to the IMS system support 
functions user guide/programmer reference, UP-8364 (current version). 
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2.7. ABNORMAL DMS TERMINATION 


When DMS abnormally terminates, the OS/3 operating system notifies IMS that an 
abnormal DMS termination occurred. IMS continues running while DMS shuts down. IMS 
cancels any active transactions that access the data base, rolls back updates, and sends 
an error message to the terminals initiating those transactions. Transactions attempting to 
access the data base after the DMS shutdown are also canceled. 


You must restart DMS before you can access the data base using IMS action programs. 
For a detailed description on restarting DMS, refer to the DMS system support functions 
user guide/programmer reference, UP-8272 (current version). 
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7.5. EXECUTING THE EXAMPLE ACTION PROGRAM 


With the DBMS still loaded, the job control stream in Figure 7-17 starts up IMS in offline batch 
mode to execute the example action program. Fifty input messages are embedded in the job 
control stream. The transaction code STATE in each message initiates the action program to 
retrieve the desired data from the data base. 


In an online IMS environment, the input messages would be entered interactively at IMS 
terminals and you would load ICAM before starting up IMS. Refer to the IMS system support 
functions user guide/programmer reference, UP-8364 (current version) for the complete start- 
up procedure. 


JOB IMSMT,,16000,,4 

DVvC 20 // LFo PRNTR 

DVC 21 // LFbD PRNTRI 

DVC 50 4/ VOL IMSUMS *DBA LIBRARY® 7/7 LED DBALIB 
DVC 50 7/ VOW IMSDMS AUDFILE // LFD AUDFILE 

DVC 50 // VOL IMSDMS CONDATA 7/ LFD CONDATA 

ovCc sO 4/7 VOL IMSOMS NAMEREC // LFD NAMEREC 

EXEC IMSMT,DBALIB 

PARAM BATCHSOFFLINE 


STATE ALABAMA 
STATE ALASKA 
STATE ARIZONA 
STATE ARKANSAS 
STATE CALIFORNIA 
STATE COLURADO 
STATE CONNECTICUT 
STATE DELAWARE 
STATE FLORIDA 
STATE GEORGIA 
STATE HAWAII 
STATE IDAHO 

STATE ILLINOIS 
STATE INDIANA 
STATE IOWA 

STATE KANSAS 
STATE KENTUCKY 
STATE LOUISIANA 
STATE MAINE 

STATE MARYLAND 
STATE MASSACHUSETTS 
STATE MICHIGAN 
STATE MINNESOTA 
STATE MISSISSIPPI 
STATE MISSOURI 
STATE MONTANA 
STATE NEBKASKA 
STATE NEVADA 





Figure 7—17. Starting Up IMS to Execute the Action Program (Part 1 of 2) 
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STATE NEw HAMPSHIRE 
STATE NEW JERSEY 
STATE NEW MEXICO 
STATE NEW YORK 
STATE NORTH CAROLINA 
STATE NORTH DAKOTA 
STATE OHI1OU 

STATE OKLAHOMA 
STATE OREGON 

STATE PENNSYLVANIA 
STATE RHOVE ISLAND 
STATE SOUTH CAROLINA 
STATE SOUTH DAKOTA 
STATE TENNESSEE 
STATE TEXAS 

STATE UTAH 

STATE VERMONT 

STATE VIRGINIA 
STATE WASHINGTON 
STATE WEST VIRGINIA 
STATE WISCONSIN 
STATE WYOMING 

/* 

/%& 

4// FIN 





Figure 7—17. Starting Up IMS to Execute the Action Program (Part 2 of 2} 


7.6. SHUTTING DOWN IMS AND DMS 


Because IMS was started up in offline batch mode, you do not have to shut down IMS. In an 
online environment, you would shut down IMS with the master terminal command: 


ZZSHD 


The final step is to shut down the DBMS with the operator command: 


n@ SHUTDOWN DBMS. 
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Appendix A. DMS Rollback 
Error Codes 
Returned to IMS 


When an error occurs during the execution of a DMS verb, DMS informs the calling 
program by returning an error code in the DMCA, in either or both of the fields ERROR- 
STATUS and RB-ERROR-CODE. If either of these fields contains a non-zero value, an error 
has occurred. 


DMS errors are either fatal or nonfatal. For fatal errors, both ERROR-STATUS and RB- 
ERROR-CODE contain nonzero values. For nonfatal errors, only ERROR-STATUS contains 
a nonzero value. 


DMS run units automatically check for fatal errors because the DML preprocessor inserts 
an “IF RB-ERROR-CODE NOT EQUAL TO ZEROS GOTO...” statement after each DMS 
verb. This statement directs program control to the rollback paragraph that the user 
specified in the INVOKE statement. To check for nonfatal errors, the user should include a 
“PERFORM DMS-STATUS.” statement after each statement in his program that contains a 
DML verb. 


When a nonfatal error occurs (that is, RB-ERROR-CODE is zero but ERROR-STATUS is 
not), the first two bytes of ERROR-STATUS contain the major verb code and the last two 
bytes indicate the specific error. For the interpretation of these codes, see the data base 
management system (DMS) data manipulation language user guide/programmer 
reference, UP-8036 (current version). 


When a fatal error occurs, the last two bytes of ERROR-STATUS contain ‘59’, signifying 
that DMS has forced a DEPART WITH ROLLBACK on behalf of the run unit. The RB- 
ERROR-CODE field, which is also divided into two parts, provides further information. The 
last two bytes of RB-ERROR-CODE give the reason for the rollback, and the first two show 
whether the rollback succeeded. If these first two bytes contain zeros, the rollback 
succeeded; otherwise, the rollback failed for the reason indicated. The codes returned in 
RB-ERROR-CODE are described in the DMS data manipulation language user 
guide/programmer reference, UP-8036 (current version). 
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For multithread IMS (as well as for batch DMS run units), the use of the DMCA error 
fields is as described in this appendix and in the current version of UP-8036. Single-thread 
IMS generally follows the same conventions, but there are exceptions. For a few fatal 
error conditions, IMS returns a slightly different error code. If the last two bytes of ERROR- 
STATUS are “59”, you should interpret the RB-ERROR-CODE field as previously described. 
If, however, the last two bytes of ERROR-STATUS are zero, the first two bytes of RB- 
ERROR-CODE have the following meaning: 


Last Two Bytes of Normal DMS 


RB-ERROR-CODE Equivalent Meaning 

01 59 IMS not allowed with DMS 
02 97 Unable to call DMS 

03 40 IMS terminal limit exceeded 
04 99 Run unit not bound 

NOTE: 


Do not confuse the “59” shown in this list with the “59” that may appear in the last 
two bytes of ERROR-STATUS. These are two unrelated uses of the number “59”. 


For these four error conditions, IMS also sends the terminal operator a message 
describing the error. These messages are: 


DMCA Error Code IMS Message 


0001 DMSO2 DMS WOULD NOT PERMIT IMS ACCESS 
0002 DMSO1 IMS COULD NOT CALL DMS SYMBIONT 
0003 DMSO5 IMPART WAS NOT SUCCESSFUL 


0004 DMSO9 ACTION DID NOT ISSUE IMPART FIRST 
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